// 定义包路径，属于驾校模块的Web控制器层，用于处理职工相关请求
package com.ruoyi.web.controller.jiaxiao;

// 导入Java工具类，用于处理集合数据
import java.util.List;
// 导入Spring依赖注入注解，用于自动装配服务层对象
import org.springframework.beans.factory.annotation.Autowired;
// 导入Spring MVC注解，用于定义请求映射、接收请求参数等
import org.springframework.web.bind.annotation.*;
// 导入Spring Web多媒体相关类，用于处理文件上传
import org.springframework.web.multipart.MultipartFile;
// 导入Spring Security注解，用于方法级别的权限控制
import org.springframework.security.access.prepost.PreAuthorize;
// 导入系统自定义注解，用于记录操作日志
import com.ruoyi.common.annotation.Log;
// 导入系统基础控制器，提供分页、结果封装等通用功能
import com.ruoyi.common.core.controller.BaseController;
// 导入系统统一响应格式类，用于封装接口返回结果
import com.ruoyi.common.core.domain.AjaxResult;
// 导入系统分页数据封装类，用于表格分页查询结果返回
import com.ruoyi.common.core.page.TableDataInfo;
// 导入系统业务操作类型枚举，用于日志记录操作类型
import com.ruoyi.common.enums.BusinessType;
// 导入系统Excel工具类，用于Excel导出、导入操作
import com.ruoyi.common.utils.poi.ExcelUtil;
// 导入职工实体类，对应数据库表结构
import com.ruoyi.system.domain.JxStaff;
// 导入职工服务层接口，定义职工相关业务逻辑
import com.ruoyi.system.service.IJxStaffService;

// 标识当前类为REST风格控制器，返回数据默认以JSON格式响应
@RestController
// 定义当前控制器的基础请求路径，所有接口路径前缀为"/jiaxiao/staff"
@RequestMapping("/jiaxiao/staff")
// 继承基础控制器，复用分页、结果转换等通用方法
public class JxStaffController extends BaseController {

    // 自动装配职工服务层实现类，由Spring容器管理依赖
    @Autowired
    private IJxStaffService jxStaffService;

    /**
     * 查询职工列表
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:list"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:list')")
    // 定义GET请求路径，完整接口路径为"/jiaxiao/staff/list"
    @GetMapping("/list")
    // 接收JxStaff类型的查询参数（自动从请求参数中绑定），返回分页表格数据
    public TableDataInfo list(JxStaff query) {
        // 启动分页：从请求中获取页码、每页条数等参数，初始化分页条件
        startPage();
        // 调用服务层方法，根据查询条件查询职工列表
        List<JxStaff> list = jxStaffService.selectJxStaffList(query);
        // 将查询结果转换为TableDataInfo格式（包含总条数、分页数据），返回给前端
        return getDataTable(list);
    }

    /**
     * 获取职工详细信息
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:query"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:query')")
    // 定义GET请求路径，{staffId}为路径参数（职工ID），完整路径为"/jiaxiao/staff/{staffId}"
    @GetMapping("/{staffId}")
    // 通过@PathVariable注解接收路径参数staffId，返回职工详细信息
    public AjaxResult getInfo(@PathVariable Long staffId) {
        // 调用服务层方法查询指定ID的职工信息，用success方法封装为成功响应
        return success(jxStaffService.selectJxStaffById(staffId));
    }

    /**
     * 新增职工
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:add"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:add')")
    // 日志注解：记录操作标题为"职工"，业务类型为"新增"（INSERT）
    @Log(title = "职工", businessType = BusinessType.INSERT)
    // 定义POST请求路径，完整接口路径为"/jiaxiao/staff"
    @PostMapping
    // 通过@RequestBody注解接收JSON格式的职工实体参数，新增职工数据
    public AjaxResult add(@RequestBody JxStaff entity) {
        // 调用服务层新增方法，toAjax方法将服务层返回的影响行数转换为AjaxResult响应
        return toAjax(jxStaffService.insertJxStaff(entity));
    }

    /**
     * 修改职工
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:edit"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:edit')")
    // 日志注解：记录操作标题为"职工"，业务类型为"更新"（UPDATE）
    @Log(title = "职工", businessType = BusinessType.UPDATE)
    // 定义PUT请求路径，完整接口路径为"/jiaxiao/staff"
    @PutMapping
    // 通过@RequestBody注解接收JSON格式的职工实体参数，修改职工数据
    public AjaxResult edit(@RequestBody JxStaff entity) {
        // 调用服务层修改方法，toAjax方法将影响行数转换为AjaxResult响应
        return toAjax(jxStaffService.updateJxStaff(entity));
    }

    /**
     * 删除职工
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:remove"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:remove')")
    // 日志注解：记录操作标题为"职工"，业务类型为"删除"（DELETE）
    @Log(title = "职工", businessType = BusinessType.DELETE)
    // 定义DELETE请求路径，{staffIds}为路径参数（多个职工ID，用逗号分隔）
    @DeleteMapping("/{staffIds}")
    // 通过@PathVariable注解接收路径参数（转换为Long数组），批量删除职工
    public AjaxResult remove(@PathVariable Long[] staffIds) {
        // 调用服务层批量删除方法，toAjax方法将影响行数转换为AjaxResult响应
        return toAjax(jxStaffService.deleteJxStaffByIds(staffIds));
    }

    /**
     * 导出职工列表
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:export"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:export')")
    // 日志注解：记录操作标题为"职工"，业务类型为"导出"（EXPORT）
    @Log(title = "职工", businessType = BusinessType.EXPORT)
    // 定义POST请求路径，完整接口路径为"/jiaxiao/staff/export"
    @PostMapping("/export")
    // 接收JxStaff类型的查询参数，导出符合条件的职工数据为Excel
    public AjaxResult export(JxStaff query) {
        // 调用服务层方法，查询符合条件的职工列表（不分页）
        List<JxStaff> list = jxStaffService.selectJxStaffList(query);
        // 创建Excel工具类实例，指定导出数据类型为JxStaff
        ExcelUtil<JxStaff> util = new ExcelUtil<>(JxStaff.class);
        // 调用工具类导出方法，返回包含Excel文件流的AjaxResult响应
        return util.exportExcel(list, "职工数据");
    }

    /**
     * 导入职工数据
     */
    // 方法级别权限控制：只有拥有"jiaxiao:staff:import"权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:staff:import')")
    // 日志注解：记录操作标题为"职工"，业务类型为"导入"（IMPORT）
    @Log(title = "职工", businessType = BusinessType.IMPORT)
    // 定义POST请求路径，完整接口路径为"/jiaxiao/staff/importData"
    @PostMapping("/importData")
    // 接收文件上传参数（MultipartFile）和更新支持参数，抛出异常交由全局异常处理
    public AjaxResult importData(MultipartFile file, boolean updateSupport) throws Exception {
        // 创建Excel工具类实例，指定导入数据类型为JxStaff
        ExcelUtil<JxStaff> util = new ExcelUtil<>(JxStaff.class);
        // 从上传文件的输入流中读取数据，转换为JxStaff列表
        List<JxStaff> list = util.importExcel(file.getInputStream());
        // 初始化成功导入的记录数
        int success = 0;
        // 遍历导入的职工列表，逐条处理
        for (JxStaff s : list) {
            // 如果支持更新且职工ID不为空（表示存在已有记录），则执行更新操作
            if (updateSupport && s.getStaffId() != null) {
                jxStaffService.updateJxStaff(s);
            } else {
                // 否则执行新增操作
                jxStaffService.insertJxStaff(s);
            }
            // 成功条数自增
            success++;
        }
        // 返回导入成功的记录数
        return AjaxResult.success("导入成功" + success + "条");
    }

    /**
     * 下载职工导入模板
     */
    // 定义POST请求路径，完整接口路径为"/jiaxiao/staff/importTemplate"
    @PostMapping("/importTemplate")
    // 下载职工数据导入的Excel模板文件
    public AjaxResult importTemplate() {
        // 创建Excel工具类实例，指定模板对应的数据类型为JxStaff
        ExcelUtil<JxStaff> util = new ExcelUtil<>(JxStaff.class);
        // 调用工具类生成模板方法，返回包含模板文件流的AjaxResult响应
        return util.importTemplateExcel("职工数据");
    }
}